
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
  <head>
    <meta charset="utf-8" />
    <title>解析参数并构建值变量 &#8212; Python 3.7.8 文档</title>
    <link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/translations.js"></script>
    
    <script type="text/javascript" src="../_static/sidebar.js"></script>
    
    <link rel="search" type="application/opensearchdescription+xml"
          title="在 Python 3.7.8 文档 中搜索"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="关于这些文档" href="../about.html" />
    <link rel="index" title="索引" href="../genindex.html" />
    <link rel="search" title="搜索" href="../search.html" />
    <link rel="copyright" title="版权所有" href="../copyright.html" />
    <link rel="next" title="字符串转换与格式化" href="conversion.html" />
    <link rel="prev" title="数据 marshal 操作支持" href="marshal.html" />
    <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
    <link rel="canonical" href="https://docs.python.org/3/c-api/arg.html" />
    
    <script type="text/javascript" src="../_static/copybutton.js"></script>
    
    
    
    
    <style>
      @media only screen {
        table.full-width-table {
            width: 100%;
        }
      }
    </style>
 

  </head><body>
  
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>导航</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="总目录"
             accesskey="I">索引</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python 模块索引"
             >模块</a> |</li>
        <li class="right" >
          <a href="conversion.html" title="字符串转换与格式化"
             accesskey="N">下一页</a> |</li>
        <li class="right" >
          <a href="marshal.html" title="数据 marshal 操作支持"
             accesskey="P">上一页</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="https://www.python.org/">Python</a> &#187;</li>
        <li>
          <a href="../index.html">3.7.8 Documentation</a> &#187;
        </li>

          <li class="nav-item nav-item-1"><a href="index.html" >Python/C API 参考手册</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">工具</a> &#187;</li>
    <li class="right">
        

    <div class="inline-search" style="display: none" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="快速搜索" type="text" name="q" />
          <input type="submit" value="转向" />
          <input type="hidden" name="check_keywords" value="yes" />
          <input type="hidden" name="area" value="default" />
        </form>
    </div>
    <script type="text/javascript">$('.inline-search').show(0);</script>
         |
    </li>

      </ul>
    </div>    

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="parsing-arguments-and-building-values">
<span id="arg-parsing"></span><h1>解析参数并构建值变量<a class="headerlink" href="#parsing-arguments-and-building-values" title="永久链接至标题">¶</a></h1>
<p>在创建你自己的扩展函数和方法时，这些函数是有用的。其它的信息和样例见 <a class="reference internal" href="../extending/index.html#extending-index"><span class="std std-ref">扩展和嵌入 Python 解释器</span></a> 。</p>
<p>这些函数描述的前三个，<a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>，<a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a>，以及 <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse()</span></code></a>，它们都使用 <em>格式化字符串</em> 来将函数期待的参数告知函数。这些函数都使用相同语法规则的格式化字符串。</p>
<div class="section" id="parsing-arguments">
<h2>解析参数<a class="headerlink" href="#parsing-arguments" title="永久链接至标题">¶</a></h2>
<p>一个格式化字符串包含0或者更多的格式单元。一个格式单元用来描述一个Python对象；它通常是一个字符或者由括号括起来的格式单元序列。除了少数例外，一个非括号序列的格式单元通常对应这些函数的具有单一地址的参数。在接下来的描述中，双引号内的表达式是格式单元；圆括号()内的是对应这个格式单元的Python对象类型；方括号[]内的是传递的C变量(变量集)类型。</p>
<div class="section" id="strings-and-buffers">
<h3>字符串和缓存区<a class="headerlink" href="#strings-and-buffers" title="永久链接至标题">¶</a></h3>
<p>这些格式允许将对象按照连续的内存块形式进行访问。你没必要提供返回的unicode字符或者字节区的原始数据存储。</p>
<p>一般的，当一个表达式设置一个指针指向一个缓冲区，这个缓冲区可以被相应的Python对象管理，并且这个缓冲区共享这个对象的生存周期。你不需要人为的释放任何内存空间。除了这些 <code class="docutils literal notranslate"><span class="pre">es</span></code>, <code class="docutils literal notranslate"><span class="pre">es#</span></code>, <code class="docutils literal notranslate"><span class="pre">et</span></code> and <code class="docutils literal notranslate"><span class="pre">et#</span></code>.</p>
<p>然而，当一个 <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> 结构被赋值，其包含的缓冲区被锁住，所以调用者在随后使用这个缓冲区，即使在 <a class="reference internal" href="init.html#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></code></a> 块中，可以避免可变数据因为调整大小或者被销毁所带来的风险。因此，<strong>你不得不调用</strong> <a class="reference internal" href="buffer.html#c.PyBuffer_Release" title="PyBuffer_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_Release()</span></code></a> 在你结束数据的处理时(或者在之前任何中断事件中)</p>
<p>除非另有说明，缓冲区是不会以空终止的。</p>
<p>某些格式需要只读的 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>，并设置指针而不是缓冲区结构。 他们通过检查对象的 <a class="reference internal" href="typeobj.html#c.PyBufferProcs.bf_releasebuffer" title="PyBufferProcs.bf_releasebuffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyBufferProcs.bf_releasebuffer</span></code></a> 字段是否为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 来发挥作用，该字段不允许为 <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> 这样的可变对象。</p>
<div class="admonition note">
<p class="admonition-title">注解</p>
<p>所有 <code class="docutils literal notranslate"><span class="pre">#</span></code> 表达式的变式(<code class="docutils literal notranslate"><span class="pre">s#</span></code>，<code class="docutils literal notranslate"><span class="pre">y#</span></code>，等等)，长度参数的类型(整型或者 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>)在包含 <code class="file docutils literal notranslate"><span class="pre">Python.h</span></code> 头文件之前由 <code class="xref c c-macro docutils literal notranslate"><span class="pre">PY_SSIZE_T_CLEAN</span></code> 宏的定义控制。如果这个宏被定义，长度是一个 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> Python元大小类型而不是一个 <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型。在未来的Python版本中将会改变，只支持 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> 而放弃支持 <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型。最好一直定义 <code class="xref c c-macro docutils literal notranslate"><span class="pre">PY_SSIZE_T_CLEAN</span></code> 这个宏。</p>
</div>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">s</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const char *]</dt><dd><p>将一个Unicode对象转换成一个指向字符串的C指针。一个指针指向一个已经存在的字符串，这个字符串存储的是传如的字符指针变量。C字符串是已空结束的。Python字符串不能包含嵌入的无效的代码点；如果由，一个 <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> 异常会被引发。Unicode对象被转化成 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码的C字符串。如果转换失败，一个 <a class="reference internal" href="../library/exceptions.html#UnicodeError" title="UnicodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeError</span></code></a> 异常被引发。</p>
<div class="admonition note">
<p class="admonition-title">注解</p>
<p>这个表达式不接受 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>。如果你想接受文件系统路径并将它们转化成C字符串，建议使用 <code class="docutils literal notranslate"><span class="pre">O&amp;</span></code> 表达式配合 <a class="reference internal" href="unicode.html#c.PyUnicode_FSConverter" title="PyUnicode_FSConverter"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_FSConverter()</span></code></a> 作为 <em>转化函数</em>。</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.5 版更改: </span>以前，当Python字符串中遇到了嵌入的null代码点会引发 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> 。</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">s*</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [Py_buffer]</dt><dd><p>这个表达式既接受Unicode对象也接受类字节类型对象。它为由调用者提供的 <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> 结构赋值。这里结果的C字符串可能包含嵌入的NUL字节。Unicode对象通过 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码转化成C字符串。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">s#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, 只读 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [const char *, int or <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>像 <code class="docutils literal notranslate"><span class="pre">s*</span></code>，除了它不接受易变的对象。结果存储在两个C 变量中，第一个是指向C字符串的指针，第二个是它的长度。字符串可能包含嵌入的null字节。Unicode对象都被通过 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码转化成C字符串。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">s</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下，C 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z*</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [Py_buffer]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">s*</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下，<a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> 结构的 <code class="docutils literal notranslate"><span class="pre">buf</span></code> 成员设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, 只读 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int or <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">s#</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下，C 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">y</span></code> (read-only <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [const char *]</dt><dd><p>这个表达式将一个类字节类型对象转化成一个指向字符串的C指针；它不接受Unicode对象。字节缓存区必须不包含嵌入的null字节；如果包含了null字节，会引发一个 <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> 异常。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.5 版更改: </span>以前，当字节缓冲区中遇到了嵌入的null字节会引发 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> 。</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">y*</span></code> (<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [Py_buffer]</dt><dd><p><code class="docutils literal notranslate"><span class="pre">s*</span></code> 的变式，不接受Unicode对象，只接受类字节类型变量。<strong>这是接受二进制数据的推荐方法</strong>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">y#</span></code> (只读 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [const char *, int or <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>This variant on <code class="docutils literal notranslate"><span class="pre">s#</span></code> doesn't accept Unicode objects, only bytes-like
objects.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>) [PyBytesObject *]</dt><dd><p>要求Python对象是一个 <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 类型对象，没有尝试任何的转换。如果不是一个字节类型对象会引发 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> 异常。C变量也可能声明为 <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> 类型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Y</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>) [PyByteArrayObject *]</dt><dd><p>要求Python对象是一个 <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> 类型对象，没有尝试任何的转换。如果不是一个 <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> 类型对象会引发 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> 异常。C变量也可能声明为 <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> 类型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const Py_UNICODE *]</dt><dd><p>将一个Python Unicode对象转化成指向一个以空终止的Unicode字符缓冲区的指针。你必须传入一个 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> 指针变量的地址，存储了一个指向已经存在的Unicode缓冲区的指针。请注意一个 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> 类型的字符宽度取决于编译选项(16位或者32位)。Python字符串必须不能包含嵌入的null代码点；如果有，引发一个 <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> 异常。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.5 版更改: </span>以前，当Python字符串中遇到了嵌入的null代码点会引发 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> 。</p>
</div>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>这是旧版样式 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; 请迁移至 <a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const Py_UNICODE *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p><code class="docutils literal notranslate"><span class="pre">u</span></code> 的变式，存储两个C变量，第一个指针指向一个Unicode数据缓存区，第二个是它的长度。它允许null代码点。</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>这是旧版样式 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; 请迁移至 <a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Z</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const Py_UNICODE *]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">u</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>这是旧版样式 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; 请迁移至 <a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Z#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const Py_UNICODE *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>与 <code class="docutils literal notranslate"><span class="pre">u#</span></code> 类似，但 Python 对象也可能为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> 指针设置为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.3, will be removed in version 4.0: </span>这是旧版样式 <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> API; 请迁移至 <a class="reference internal" href="unicode.html#c.PyUnicode_AsWideCharString" title="PyUnicode_AsWideCharString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_AsWideCharString()</span></code></a>.</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">U</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [PyObject *]</dt><dd><p>要求Python对象是一个Unicode对象，没有尝试任何的转换。如果不是一个Unicode对象会引发 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> 异常。C变量也可能声明为 <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> 类型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">w*</span></code> (可读写 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>) [Py_buffer]</dt><dd><p>这个表达式接受任何实现可读写缓存区接口的对象。它为调用者提供的 <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> 结构赋值。缓冲区可能存在嵌入的null字节。当缓冲区使用完后调用者需要调用 <a class="reference internal" href="buffer.html#c.PyBuffer_Release" title="PyBuffer_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_Release()</span></code></a>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">es</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const char *encoding, char **buffer]</dt><dd><p><code class="docutils literal notranslate"><span class="pre">s</span></code> 的变式，它将编码后的Unicode字符存入字符缓冲区。它只处理没有嵌入NUL字节的已编码数据</p>
<p>此格式需要两个参数。 第一个仅用作输入，并且必须是 <code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code>，该名称将编码的名称指向 NUL 终止字符串或&quot;NULL&quot;，在这种情况下，使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码。如果 Python 不知道命名编码，则引发异常。 第二个参数必须为 <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code> 它引用的指针的值将设置为包含参数文本内容的缓冲区。文本将以第一个参数指定的编码进行编码。</p>
<p><a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> 会分配一个足够大小的缓冲区，将编码后的数据拷贝进这个缓冲区并且设置 <em>*buffer</em> 引用这个新分配的内存空间。调用者有责任在使用后调用 <a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a> 去释放已经分配的缓冲区。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">et</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>) [const char *encoding, char **buffer]</dt><dd><p>和 <code class="docutils literal notranslate"><span class="pre">es</span></code> 相同，除了不用重编码传入的字符串对象。相反，它假设传入的参数是编码后的字符串类型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">es#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const char *encoding, char **buffer, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> *buffer_length]</dt><dd><p><code class="docutils literal notranslate"><span class="pre">s#</span></code> 的变式，它将已编码的Unicode字符存入字符缓冲区。不像 <code class="docutils literal notranslate"><span class="pre">es</span></code> 表达式，它允许传入的数据包含NUL字符。</p>
<p>它需要三个参数。 第一个仅用作输入，并且必须为 <code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code>，该对象指向一个编码格式名称，形式为以 NUL 结束的字符串或 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，在后一种情况下将使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码格式。 如果编码格式名称无法被 Python 识别则会引发异常。 第二个参数必须为 <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code>；它所引用的指针的值将被设为包含参数文本内容的缓冲区。 文本将以第一个参数所指定的编码格式进行编码。 第三个参数必须是指向一个整数的指针；所引用的整数将被设为输出缓冲区中的字节数。</p>
<p>有两种操作方式：</p>
<p>如果 <em>*buffer</em> 指向 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 指针，则函数将分配所需大小的缓冲区，将编码的数据复制到此缓冲区，并设置 <em>*buffer</em> 以引用新分配的存储。 呼叫者负责调用 <a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a> 以在使用后释放分配的缓冲区。</p>
<p>如果 <em>*buffer</em> 指向非 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 指针（已分配的缓冲区），则 <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> 将使用此位置作为缓冲区，并将 <em>*buffer_length</em> 的初始值解释为缓冲区大小。 然后，它将将编码的数据复制到缓冲区，并终止它。 如果缓冲区不够大，将设置一个 <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>。</p>
<p>在这两个例子中，<em>*buffer_length</em> 被设置为编码后结尾不为NUL的数据的长度。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">et#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 或 <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>) [const char *encoding, char **buffer, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> *buffer_length]</dt><dd><p>和 <code class="docutils literal notranslate"><span class="pre">es#</span></code> 相同，除了不用重编码传入的字符串对象。相反，它假设传入的参数是编码后的字符串类型。</p>
</dd>
</dl>
</div>
<div class="section" id="numbers">
<h3>数字<a class="headerlink" href="#numbers" title="永久链接至标题">¶</a></h3>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">b</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned char]</dt><dd><p>将一个非负的Python整型转化成一个无符号的微整型，存储在一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code> 类型中。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">B</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned char]</dt><dd><p>将一个Python整型转化成一个微整型并不检查溢出问题，存储在一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code> 类型中。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">h</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [short int]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span> <span class="pre">int</span></code> 短整型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">H</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned short int]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span> <span class="pre">int</span></code> 无符号短整型，并不检查溢出问题。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">i</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [int]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">I</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned int]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code> 无符号整型，并不检查溢出问题。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">l</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long int]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code> 长整型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">k</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">int</span></code> 无符号长整型，并不检查溢出问题。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">L</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long long]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> 长长整型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">K</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long long]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code> 无符号长长整型，并不检查溢出问题。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">n</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [Py_ssize_t]</dt><dd><p>将一个Python整型转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> Python元大小类型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">c</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 或者 <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> 长度为1) [char]</dt><dd><p>将一个Python字节类型，如一个长度为1的 <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 或者 <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> 对象，转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code> 字符类型。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.3 版更改: </span>允许 <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> 类型的对象。</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">C</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 长度为1) [int]</dt><dd><p>将一个Python字符，如一个长度为1的 <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 字符串对象，转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型类型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">f</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [float]</dt><dd><p>将一个Python浮点数转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">float</span></code> 浮点数。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">d</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [double]</dt><dd><p>将一个Python浮点数转化成一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> 双精度浮点数。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">D</span></code> (<a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-class docutils literal notranslate"><span class="pre">complex</span></code></a>) [Py_complex]</dt><dd><p>将一个Python复数类型转化成一个C <a class="reference internal" href="complex.html#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> Python复数类型。</p>
</dd>
</dl>
</div>
<div class="section" id="other-objects">
<h3>其他对象<a class="headerlink" href="#other-objects" title="永久链接至标题">¶</a></h3>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt><dd><p>将 Python 对象（不进行任何转换）存储在 C 对象指针中。 因此，C 程序接收已传递的实际对象。 对象的引用计数不会增加。 存储的指针不是 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O!</span></code> (object) [<em>typeobject</em>, PyObject *]</dt><dd><p>将一个Python对象存入一个C指针。和 <code class="docutils literal notranslate"><span class="pre">O</span></code> 类似，但是需要两个C参数：第一个是Python类型对象的地址，第二个是存储对象指针的C变量( <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> 变量)的地址。如果Python对象类型不对，会抛出 <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> 异常。</p>
</dd>
</dl>
<dl id="o-ampersand">
<dt><code class="docutils literal notranslate"><span class="pre">O&amp;</span></code> (object) [<em>converter</em>, <em>anything</em>]</dt><dd><p>通过一个 <em>converter</em> 函数将一个Python对象转换成一个C变量。这需要两个参数：第一个是一个函数，第二个是一个C变量的地址(任意类型的)，转化为 <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> 类型。<em>converter</em> 函数像这样被调用：</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">status</span> <span class="o">=</span> <span class="n">converter</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">address</span><span class="p">);</span>
</pre></div>
</div>
<p><em>object*是待转化的Python对象并且 *address</em> 是传入 <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> 函数的 <code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code> 类型参数。返回的 <em>status</em> 是1代表转换成功，0代表转换失败。当转换失败，<em>converter*函数会引发一个异常并且不会修改 *address</em> 的内容。</p>
<p>如果 <em>converter</em> 返回 <code class="docutils literal notranslate"><span class="pre">Py_CLEANUP_SUPPORTED</span></code>，则如果参数解析最终失败，它可能会再次调用该函数，从而使转换器有机会释放已分配的任何内存。在第二个调用中，<em>object</em> 参数将为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>;因此，该参数将为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>;因此，该参数将为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，因此，该参数将为 <code class="docutils literal notranslate"><span class="pre">NULL``（如果值）为</span> <span class="pre">``NULL</span></code> <em>address</em> 的值与原始呼叫中的值相同。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.1 版更改: </span><code class="docutils literal notranslate"><span class="pre">Py_CLEANUP_SUPPORTED</span></code> 被添加。</p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">p</span></code> (<a class="reference internal" href="../library/functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a>) [int]</dt><dd><p>测试传入的值是否为真(一个布尔判断)并且将结果转化为相对应的C true/false整型值。如果表达式为真置``1``，假则置``0``。它接受任何合法的Python值。参见 <a class="reference internal" href="../library/stdtypes.html#truth"><span class="std std-ref">逻辑值检测</span></a> 获取更多关于Python如何测试值为真的信息。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.3 新版功能.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">(items)</span></code> (<a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>) [<em>matching-items</em>]</dt><dd><p>对象必须是Python序列，它的长度是 <em>items</em> 中格式单元的数量。C参数必须对应 <em>items</em> 中每一个独立的格式单元。序列中的格式单元可能有嵌套。</p>
</dd>
</dl>
<p>传递 “长”整型(整型的值超过了平台的 <code class="xref py py-const docutils literal notranslate"><span class="pre">LONG_MAX</span></code> 限制)是可能的，然而没有进行适当的范围检测——当接收字段太小而接收不到值时，最重要的位被静默地截断(实际上，C语言会在语义继承的基础上强制类型转换——期望的值可能会发生变化)。</p>
<p>格式化字符串中还有一些其他的字符具有特殊的涵义。这些可能并不嵌套在圆括号中。它们是：</p>
<dl>
<dt><code class="docutils literal notranslate"><span class="pre">|</span></code></dt><dd><p>表明在Python参数列表中剩下的参数都是可选的。C变量对应的可选参数需要初始化为默认值——当一个可选参数没有指定时， <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>  不能访问相应的C变量(变量集)的内容。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">$</span></code></dt><dd><p><a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a> only：表明在Python参数列表中剩下的参数都是强制关键字参数。当前，所有强制关键字参数都必须也是可选参数，所以格式化字符串中  <code class="docutils literal notranslate"><span class="pre">|</span></code> 必须一直在 <code class="docutils literal notranslate"><span class="pre">$</span></code> 前面。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.3 新版功能.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">:</span></code></dt><dd><p>格式单元的列表结束标志；冒号后的字符串被用来作为错误消息中的函数名(<a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> 函数引发的“关联值”异常)。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">;</span></code></dt><dd><p>格式单元的列表结束标志；分号后的字符串被用来作为错误消息取代默认的错误消息。 <code class="docutils literal notranslate"><span class="pre">:</span></code> 和 <code class="docutils literal notranslate"><span class="pre">;</span></code> 相互排斥。</p>
</dd>
</dl>
<p>注意任何由调用者提供的Python对象引用是 <em>借来的</em> 引用；不要递减它们的引用计数！</p>
<p>传递给这些函数的附加参数必须是由格式化字符串确定的变量的地址；这些都是用来存储输入元组的值。有一些情况，如上面的格式单元列表中所描述的，这些参数作为输入值使用；在这种情况下，它们应该匹配指定的相应的格式单元。</p>
<p>为了转换成功，<em>arg</em> 对象必须匹配格式并且格式必须用尽。成功的话，<a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> 函数返回true，反之它们返回false并且引发一个合适的异常。当 <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> 函数因为某一个格式单元转化失败而失败时，对应的以及后续的格式单元地址内的变量都不会被使用。</p>
</div>
<div class="section" id="api-functions">
<h3>API 函数<a class="headerlink" href="#api-functions" title="永久链接至标题">¶</a></h3>
<dl class="function">
<dt id="c.PyArg_ParseTuple">
int <code class="sig-name descname">PyArg_ParseTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ParseTuple" title="永久链接至目标">¶</a></dt>
<dd><p>解析一个函数的参数，表达式中的参数按参数位置顺序存入局部变量中。成功返回true；失败返回false并且引发相应的异常。</p>
</dd></dl>

<dl class="function">
<dt id="c.PyArg_VaParse">
int <code class="sig-name descname">PyArg_VaParse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_VaParse" title="永久链接至目标">¶</a></dt>
<dd><p>和 <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> 相同，然而它接受一个va_list类型的参数而不是可变数量的参数集。</p>
</dd></dl>

<dl class="function">
<dt id="c.PyArg_ParseTupleAndKeywords">
int <code class="sig-name descname">PyArg_ParseTupleAndKeywords</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em>, const char<em> *format</em>, char<em> *keywords[]</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ParseTupleAndKeywords" title="永久链接至目标">¶</a></dt>
<dd><p>分析将位置参数和关键字参数同时转换为局部变量的函数的参数。 <em>keywords</em> 参数是关键字参数名称的 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 终止数组。 空名称表示 <a class="reference internal" href="../glossary.html#positional-only-parameter"><span class="std std-ref">positional-only parameters</span></a>。成功时返回 true;发生故障时，它将返回 false 并引发相应的异常。</p>
<div class="versionchanged">
<p><span class="versionmodified changed">在 3.6 版更改: </span>添加了 <a class="reference internal" href="../glossary.html#positional-only-parameter"><span class="std std-ref">positional-only parameters</span></a> 的支持。</p>
</div>
</dd></dl>

<dl class="function">
<dt id="c.PyArg_VaParseTupleAndKeywords">
int <code class="sig-name descname">PyArg_VaParseTupleAndKeywords</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em>, const char<em> *format</em>, char<em> *keywords[]</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_VaParseTupleAndKeywords" title="永久链接至目标">¶</a></dt>
<dd><p>和 <a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a> 相同，然而它接受一个va_list类型的参数而不是可变数量的参数集。</p>
</dd></dl>

<dl class="function">
<dt id="c.PyArg_ValidateKeywordArguments">
int <code class="sig-name descname">PyArg_ValidateKeywordArguments</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ValidateKeywordArguments" title="永久链接至目标">¶</a></dt>
<dd><p>确保字典中的关键字参数都是字符串。这个函数只被使用于 <a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a> 不被使用的情况下，后者已经不再做这样的检查。</p>
<div class="versionadded">
<p><span class="versionmodified added">3.2 新版功能.</span></p>
</div>
</dd></dl>

<dl class="function">
<dt id="c.PyArg_Parse">
int <code class="sig-name descname">PyArg_Parse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_Parse" title="永久链接至目标">¶</a></dt>
<dd><p>函数被用来析构“旧类型”函数的参数列表——这些函数使用的 <code class="xref py py-const docutils literal notranslate"><span class="pre">METH_OLDARGS</span></code> 参数解析方法已从Python 3中移除。这不被推荐用于新代码的参数解析，并且在标准解释器中的大多数代码已被修改，已不再用于该目的。它仍然方便于分解其他元组，然而可能因为这个目的被继续使用。</p>
</dd></dl>

<dl class="function">
<dt id="c.PyArg_UnpackTuple">
int <code class="sig-name descname">PyArg_UnpackTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *name</em>, Py_ssize_t<em> min</em>, Py_ssize_t<em> max</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_UnpackTuple" title="永久链接至目标">¶</a></dt>
<dd><p>一个不使用格式化字符串指定参数类型的简单形式的参数检索。使用这种方法来检索参数的函数应该在函数或者方法表中声明 <a class="reference internal" href="structures.html#METH_VARARGS" title="METH_VARARGS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_VARARGS</span></code></a>。包含实际参数的元组应该以 <em>args</em> 形式被传入；它必须是一个实际的元组。元组的长度必须至少是 <em>min</em> 并且不超过 <em>max</em>； <em>min</em> 和 <em>max</em> 可能相同。额外的参数必须传递给函数，每一个参数必须是一个指向 <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> 类型变量的指针；它们将被赋值为 <em>args</em> 的值；它们将包含借来的引用。不在 <em>args</em> 里面的可选参数不会被赋值；由调用者完成初始化。函数成功则返回true并且如果 <em>args</em> 不是元组或者包含错误数量的元素则返回false；如果失败了会引发一个异常。</p>
<p>这是一个使用此函数的示例，取自 <code class="xref py py-mod docutils literal notranslate"><span class="pre">_weakref</span></code> 帮助模块用来弱化引用的源代码：</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span>
<span class="nf">weakref_ref</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span>
<span class="p">{</span>
    <span class="n">PyObject</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
    <span class="n">PyObject</span> <span class="o">*</span><span class="n">callback</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
    <span class="n">PyObject</span> <span class="o">*</span><span class="n">result</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>

    <span class="k">if</span> <span class="p">(</span><span class="n">PyArg_UnpackTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">&quot;ref&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">object</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">callback</span><span class="p">))</span> <span class="p">{</span>
        <span class="n">result</span> <span class="o">=</span> <span class="n">PyWeakref_NewRef</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">callback</span><span class="p">);</span>
    <span class="p">}</span>
    <span class="k">return</span> <span class="n">result</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>这个例子中调用 <a class="reference internal" href="#c.PyArg_UnpackTuple" title="PyArg_UnpackTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_UnpackTuple()</span></code></a> 完全等价于调用 <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyArg_ParseTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">&quot;O|O:ref&quot;</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">object</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">callback</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

</div>
</div>
<div class="section" id="building-values">
<h2>创建变量<a class="headerlink" href="#building-values" title="永久链接至标题">¶</a></h2>
<dl class="function">
<dt id="c.Py_BuildValue">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="sig-name descname">Py_BuildValue</code><span class="sig-paren">(</span>const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.Py_BuildValue" title="永久链接至目标">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>基于类似于 <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> 函数系列和一系列值的格式字符串创建新值。 在出现错误时返回值或 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>;如果返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，将引发异常。</p>
<p><a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> 并不一直创建一个元组。只有当它的格式化字符串包含两个或更多的格式单元才会创建一个元组。如果格式化字符串是空，它返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>；如果它包含一个格式单元，它返回由格式单元描述的的任一对象。用圆括号包裹格式化字符串可以强制它返回一个大小为0或者1的元组</p>
<p>当内存缓存区的数据以参数形式传递用来构建对象时，如 <code class="docutils literal notranslate"><span class="pre">s</span></code> 和 <code class="docutils literal notranslate"><span class="pre">s#</span></code> 格式单元，会拷贝需要的数据。调用者提供的缓冲区从来都不会被由 <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> 创建的对象来引用。换句话说，如果你的代码调用 <code class="xref c c-func docutils literal notranslate"><span class="pre">malloc()</span></code> 并且将分配的内存空间传递给 <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>，你的代码就有责任在 <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> 返回时调用 <code class="xref c c-func docutils literal notranslate"><span class="pre">free()</span></code> 。</p>
<p>在下面的描述中，双引号的表达式使格式单元；圆括号()内的是格式单元将要返回的Python对象类型；方括号[]内的是传递的C变量(变量集)的类型</p>
<p>字符例如空格，制表符，冒号和逗号在格式化字符串中会被忽略(但是不包括格式单元，如 <code class="docutils literal notranslate"><span class="pre">s#</span></code>)。这可以使很长的格式化字符串具有更好的可读性。</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">s</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码将空终止的 C 字符串转换为 Python <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 对象。如果 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则使用 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">s#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>使用 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> 编码将 C 字符串及其长度转换为 Python <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 对象。如果 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则长度将被忽略，并返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">y</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>) [const char *]</dt><dd><p>这将 C 字符串转换为 Python <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 对象。 如果 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">y#</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>这会将 C 字符串及其长度转换为一个 Python 对象。 如果该 C 字符串指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>和``s``一样。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>和``s#``一样。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const wchar_t *]</dt><dd><p>将空终止的 <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> 的 Unicode （UTF-16 或 UCS-4） 数据缓冲区转换为 Python Unicode 对象。 如果 Unicode 缓冲区指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) [const wchar_t *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>将 Unicode （UTF-16 或 UCS-4） 数据缓冲区及其长度转换为 Python Unicode 对象。  如果 Unicode 缓冲区指针为 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，则长度将被忽略，并返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">U</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt><dd><p>和``s``一样。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">U#</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 或 <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *, int 或 <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>]</dt><dd><p>和``s#``一样。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">i</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [int]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">b</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [char]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code> 字符型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">h</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [short int]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span> <span class="pre">int</span></code> 短整型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">l</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long int]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code> 长整型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">B</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned char]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code> 无符号字符型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">H</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned short int]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> 无符号短整型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">I</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned int]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> 无符号整型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">k</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> 无符号长整型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">L</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [long long]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> 长长整形转化成Python整形对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">K</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [unsigned long long]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code> 无符号长长整型转化成Python整型对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">n</span></code> (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>) [Py_ssize_t]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> 类型转化为Python整型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">c</span></code> (<a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 长度为1 ) [char]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型代表的字符转化为Python <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> 长度为1的字节对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">C</span></code> (<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 长度为1) [int]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> 整型代表的字符转化为Python <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> 长度为1的字符串对象。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">d</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [double]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> 双精度浮点数转化为Python浮点数类型数字。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">f</span></code> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>) [float]</dt><dd><p>将一个C <code class="xref c c-type docutils literal notranslate"><span class="pre">float</span></code> 单精度浮点数转化为Python浮点数类型数字。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">D</span></code> (<code class="xref py py-class docutils literal notranslate"><span class="pre">复数</span></code>) [Py_complex *]</dt><dd><p>将一个C <a class="reference internal" href="complex.html#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> 类型的结构转化为Python复数类型。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt><dd><p>将 Python 对象传递不变（其引用计数除外，该计数由 1 递增）。 如果传入的对象是 <code class="docutils literal notranslate"><span class="pre">NULL</span></code> 指针，则假定这是由于生成参数的调用发现错误并设置异常而引起的。因此，<a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> 将返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>，但不会引发异常。 如果尚未引发异常，则设置 <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> (object) [PyObject *]</dt><dd><p>和``O``相同。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">N</span></code> (object) [PyObject *]</dt><dd><p>和``O``相同，然而它并不增加对象的引用计数。当通过调用参数列表中的对象构造器创建对象时很实用。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O&amp;</span></code> (object) [<em>converter</em>, <em>anything</em>]</dt><dd><p>通过 <em>converter</em> 函数将 <em>anything</em> 转换为 Python 对象。 该函数以 <em>anything</em> （应与 <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> 兼容）作为其参数，应返回 &quot;new&quot; Python 对象，如果发生错误，则应返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">(items)</span></code> (<a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>) [<em>matching-items</em>]</dt><dd><p>将一个C变量序列转换成Python元组并保持相同的元素数量</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[items]</span></code> (<a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>) [<em>相关的元素</em>]</dt><dd><p>将一个C变量序列转换成Python列表并保持相同的元素数量</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">{items}</span></code> (<a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>) [<em>相关的元素</em>]</dt><dd><p>将一个C变量序列转换成Python字典。每一对连续的C变量对作为一个元素插入字典中，分别作为关键字和值。</p>
</dd>
</dl>
<p>如果格式字符串中出现错误，则设置 <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> 异常并返回 <code class="docutils literal notranslate"><span class="pre">NULL</span></code>。</p>
</dd></dl>

<dl class="function">
<dt id="c.Py_VaBuildValue">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="sig-name descname">Py_VaBuildValue</code><span class="sig-paren">(</span>const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_VaBuildValue" title="永久链接至目标">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>和 <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> 相同，然而它接受一个va_list类型的参数而不是可变数量的参数集。</p>
</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">目录</a></h3>
  <ul>
<li><a class="reference internal" href="#">解析参数并构建值变量</a><ul>
<li><a class="reference internal" href="#parsing-arguments">解析参数</a><ul>
<li><a class="reference internal" href="#strings-and-buffers">字符串和缓存区</a></li>
<li><a class="reference internal" href="#numbers">数字</a></li>
<li><a class="reference internal" href="#other-objects">其他对象</a></li>
<li><a class="reference internal" href="#api-functions">API 函数</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-values">创建变量</a></li>
</ul>
</li>
</ul>

  <h4>上一个主题</h4>
  <p class="topless"><a href="marshal.html"
                        title="上一章">数据 marshal 操作支持</a></p>
  <h4>下一个主题</h4>
  <p class="topless"><a href="conversion.html"
                        title="下一章">字符串转换与格式化</a></p>
  <div role="note" aria-label="source link">
    <h3>本页</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">提交 Bug</a></li>
      <li>
        <a href="https://github.com/python/cpython/blob/3.7/Doc/c-api/arg.rst"
            rel="nofollow">显示源代码
        </a>
      </li>
    </ul>
  </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>  
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>导航</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="总目录"
             >索引</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python 模块索引"
             >模块</a> |</li>
        <li class="right" >
          <a href="conversion.html" title="字符串转换与格式化"
             >下一页</a> |</li>
        <li class="right" >
          <a href="marshal.html" title="数据 marshal 操作支持"
             >上一页</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="https://www.python.org/">Python</a> &#187;</li>
        <li>
          <a href="../index.html">3.7.8 Documentation</a> &#187;
        </li>

          <li class="nav-item nav-item-1"><a href="index.html" >Python/C API 参考手册</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="utilities.html" >工具</a> &#187;</li>
    <li class="right">
        

    <div class="inline-search" style="display: none" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="快速搜索" type="text" name="q" />
          <input type="submit" value="转向" />
          <input type="hidden" name="check_keywords" value="yes" />
          <input type="hidden" name="area" value="default" />
        </form>
    </div>
    <script type="text/javascript">$('.inline-search').show(0);</script>
         |
    </li>

      </ul>
    </div>  
    <div class="footer">
    &copy; <a href="../copyright.html">版权所有</a> 2001-2020, Python Software Foundation.
    <br />
    Python 软件基金会是一个非盈利组织。
    <a href="https://www.python.org/psf/donations/">请捐助。</a>
    <br />
    最后更新于 6月 29, 2020.
    <a href="../bugs.html">发现了问题</a>？
    <br />
    使用<a href="http://sphinx.pocoo.org/">Sphinx</a>2.3.1 创建。
    </div>

  </body>
</html>